iOS-SDK

Überblick

Das native WebAR³ VPS iOS-SDK lokalisiert Nutzer:innen innerhalb von VPS-Karten mithilfe von ARKit. Das XCFramework funktioniert in UIKit-, RealityKit- und SwiftUI-Apps. Folgen Sie dem Immersal-Ablauf: Voraussetzungen prüfen, Paket hinzufügen, Berechtigungen setzen und den Dienst initialisieren.

Voraussetzungen

• iOS 12.0 oder neuer
• Xcode 12+ mit Swift 5
• Gerät mit ARKit-Unterstützung (Simulator ausgeschlossen)

Installationsoptionen

Über Swift Package Manager

1. In Xcode File → Add Packages… öffnen.
2. https://github.com/WebAR-Studio/was-vps-ios.git eingeben.
3. Gewünschten Branch oder Tag auswählen und dem Target hinzufügen.

Manuelle Integration

1. Repository klonen:

   git clone https://github.com/WebAR-Studio/was-vps-ios.git

2. WASVPS.xcframework ins Projekt ziehen.
3. Unter General → Frameworks, Libraries, and Embedded Content sicherstellen, dass das Framework eingebunden ist.

Berechtigungen konfigurieren

In Info.plist Kamera- und Standorttexte hinterlegen, damit iOS die Abfragen anzeigen kann.

<key>NSCameraUsageDescription</key>
<string>Diese App benötigt Kamerazugriff für Augmented Reality.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Der Standort wird für präzise AR-Inhalte benötigt.</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>VPSLocalization</key>
    <string>Ermöglicht präzise Lokalisierung für genaue AR-Platzierung.</string>
</dict>

VPS initialisieren

VPSBuilder.initializeVPS erzeugt eine Instanz von VPSService. Übergeben Sie ARSession, API-Key und Location IDs.

API-Key benötigt? Erhalte ihn über space.web-ar.studio oder per Mail an support@webar3.com / support@web-ar.studio.

import ARKit
import WASVPS

final class VPSDemoController: UIViewController, ARSCNViewDelegate {
    @IBOutlet private weak var sceneView: ARSCNView!
    private var configuration: ARWorldTrackingConfiguration?
    private var vps: VPSService?

    override func viewDidLoad() {
        super.viewDidLoad()
        sceneView.delegate = self
        sceneView.scene = SCNScene()

        configuration = VPSBuilder.getDefaultConfiguration()

        VPSBuilder.initializeVPS(
            arSession: sceneView.session,
            apiKey: "your-api-key",
            locationIds: ["your-location-id"],
            url: "https://was-vps.web-ar.xyz/vps/api/v3",
            gpsUsage: false,
            delegate: self
        ) { service in
            self.vps = service
            self.vps?.start()
        }
    }

    override func viewWillAppear(_ animated: Bool) {
        super.viewWillAppear(animated)
        if let configuration { sceneView.session.run(configuration) }
    }

    func renderer(_ renderer: SCNSceneRenderer, updateAtTime time: TimeInterval) {
        vps?.frameUpdated()
    }
}

extension VPSDemoController: VPSServiceDelegate {
    func positionVPS(pos: ResponseVPSPhoto) {
        print("Localized pose:", pos)
    }

    func error(err: NSError) {
        print("VPS error:", err)
    }

    func sending(requestData: UploadVPSPhoto?) {
        print("Sending localization request…")
    }
}

Den Dienst in sessionWasInterrupted stoppen und in sessionInterruptionEnded erneut starten.

RealityKit

In RealityKit werden Frames im ARSessionDelegate weitergereicht:

func session(_ session: ARSession, didUpdate frame: ARFrame) {
    vps?.frameUpdated()
}

Die restlichen Lifecycle-Methoden (start, stop, clearCustomLocPos) entsprechen dem SceneKit-Ablauf.

SwiftUI

ARSCNView oder ARView per UIViewRepresentable/UIViewControllerRepresentable einbetten. VPSService in einem ViewModel halten und start()/stop() über SwiftUI-Buttons aufrufen.

Erweiterte Einstellungen

• setCustomLocPosForFirstRequest legt eine bekannte Pose vor der ersten Anfrage fest.
• Über den url-Parameter in initializeVPS lässt sich der Endpunkt ändern (Standard: https://was-vps.web-ar.xyz/vps/api/v3).
• gpsUsage aktiviert das Mitsenden von Gerätekoordinaten.

Fehlerbehebung

• Gibt VPSBuilder.getDefaultConfiguration() nil zurück, unterstützt das Gerät kein ARKit.
• Bleiben Callbacks aus, frameUpdated() pro Frame aufrufen und API-Key + Location IDs prüfen.
• Im Ordner /examples finden Sie vollständige Beispiele für UIKit, RealityKit und SwiftUI.